I've been swimming in the dirty water
I've been swimming where the fish won't go
(The Jesus & Mary Chain, "Dirty Water")

The Source Code

Not for all systems there already compiled versions of this package available. If you can not find binaries anywhere, it seems you will have to go on. Otherwise, you can skip this chapter, as it does not contain anything you would want to know.

Availability

The source archive should be available from the same locations where you are supposed to get updates from. Look out for an archive called hsc-source.lha.

Portability

Hsc was written in naked & masochistic ANSI-C. Even worse, it only uses functions of the standard library and does not require any Amiga- or Un*x-specific include files like <dir.h>, <String.h> or functions like ReadArgs(), stricmp() etc.

This should ensure a maximum of portability. However, the handling of filenames is a system-dependent thing, which has to be adapted for every OS. See also the section about Existing Ports.

Compiling Under RiscOS

For RiscOS, there is a special Makefile and ReadMe you can find in the riscos directory.

Compiling

Basically, compilation works like this: You will need a command line based C-compiler. The compiler must support ANSI-C. There is a Makefile which contains settings for all supported systems. You will have to comment in yours. After that you can launch the make tool and should hopefully end up with the binaries.

Ok, now all those steps in detail:

If you've compiled older versions of hsc before, remove all files of the old sources before you continue. Do not extract a newer source archive into a directory containing older ones.
Change your current directory to the source directory
Now load the Makefile into your editor. Make sure your editor is able to preserve TABs. If it does not, make might have some trouble afterwards.
Figure out which system and compiler you have, and remove the hash character (``#'') from the corresponding lines.
Go back to command line and type make. Lots of strange message should show up indicating that a compiler is started and that there are many options passed to it.
If there is an error - bad luck. If you do not know what to do now (for example starting to fool around with the Makefile, fix and report the bug) - worse luck. Go to the cinema or do something else, but forget about this software.

Compiler Warnings

If the compilation was successful, but some compiler warnings showed up, it depends if you should take it serious or not. There are certain parts of the code which declare functions and symbols, but not actually use them (they use them in debug-mode, but I did not want to clutter the source with too many #ifdefs). During linking stage this code should be kicked out anyway. You can safely ignore this.

Other warnings indicate a compiler bug. Contact your compiler vendor.

Ok, maybe not. If you think it could be a nasty one, do a bug report on hsc.

The Binaries

If all went well, you now should have created three files:

hsc/hsc
hsctools/hscdepp
hsctools/hscpitt

These are the executables. Congratulations. Mark the current day in your calendar with a red circle. After that, follow the installation instructions. (In short: put the binaries somewhere in your search-path, and setup hsc.prefs in the appropriate place.)

Cleaning Up

To remove the object files, use

make clean

To also remove binaries, temporary files, core dumps and other trash, use

make sterile

In ideal case, the source directory should then be in exactly the same state as it was before you started with the compilation.

Basic Test Run

Now it is probably a good time to check if hsc basically runs without crashing. Later in this chapter you will read how to do a more exhaustive test run, but for now simply type this into your command line:

hsc/hsc test/simple.hsc to test/simple.html status=full prefsfile=../hsc.prefs

If there now is a file test/simple.html which looks pretty much the same as test/simple.hsc, and the output on the display looks something like

hsc - html sucks completely, v0.XXX (dd-mmm-yy)
(C) T.Aglassinger/Tommy-Saftwörx. Freeware, type `hsc LICENSE' for details.
../hsc.prefs: preferences read
test/simple.hsc (9)

hsc passed this test. In this case, you can continue reading at the next heading.

But if you now see something like

*** atexit() failed: Unknown error code

on your display, you are most likely running under NeXTStep. There it seems to be a known bug of the ANSI-C function atexit() to return with in error code even in case of success. However, nobody ever cared about fixing this, and even in OpenStep 4.2 this bug still seems to be there.

As I do not care about faulty implementations of basic ANSI-C functions, you will have to change the source code to make it ignore the result of atexit(). Load source/hsc/hsc.c into your editor and change the line

if (atexit(func))

into something like

if (atexit(func) && 0)

to still call this function and add the additional exit-function, but ignore any errors returned by it. At least this is the work-around suggested to me. And no, there will not be a #ifdef NEXTSTEP for this stupid bug in the runtime library.

About Makefile.agi

If you sneaked around about in the source directory, you maybe also stumbled across a file called Makefile.agi.

Actually I don't use the normal Makefile described in the early chapters above for developing. The reason should be obvious, if you watched your compiler before. It only has been invoked a few times, but the there are several small source files.

This is simply because every sub-part of this package has a file which includes all corresponding small files into a single big one. The compiler will have to work quite a while on this, and it will take much more resources - especially memory.

But the optimizer will be more efficient (shorter and faster code), and, most important, there are no problems with any library managers, complex and hardly portable rules in the Makefile and so on.

If you just want to compile it once, this is fine for you. However, if one still develops on this package, and has to change and compile sources very often, this is not acceptable: A small change will cause the compiler to recompile large parts, lasting a very long time.

Therefor Makefile.agi uses a library manager to avoid this. It is easy for me to make sure that this specific Makefile runs on my machine, with the make tool installed on my machine. But it might not necessarily work with yours.

But the standard Makefile (probably) did. So that's why.

However, there might be one reason why you still want to partially use it:

Performing a Test Run

To test if hsc works as expected, some test data are included in source/test/. Please note that this material might not be up to date for pre-releases you have downloaded from the support-w3-page. Some of the tests might file in such releases.

The test rule is only declared in Makefile.agi. This Makefile uses some features not supported by all make tools. It has been designed to work with GNUmake, which is freely available together with it's source code (see Related Stuff).

To initiate the test sequence, simple type

make -f Makefile.agi test

from the same directory you have started the compilation before.

Technically speaking, the test run does the following: it will invoke hsc several times: some .hsc files will be used to create some .html files. These are compared with .expected files, which have been created before and contain the expected output.

For this comparison, diff --brief will used. Make sure that such a command is available before starting the test process (again, see Related Stuff if you do not have it).

Additionally, hsc will redirect messages to .msg files. These will be compared with .mex files(``messages expected'') the same way as described above.

If all works fine, `diff' should not produce any output.

But you should be aware that the test run also includes some faulty input data to test if hsc is able to cope with certain error situations. These will result in an output like

testing test/unknattr.hsc (messages only)..
hsc/hsc failed returncode 10
make: [test/unknattr.msg] Error 10 (ignored)

and should not confuse you. Only an error reported by diff counts as a failed test run.

Debug Mode

These paragraphs are most likely only interesting for freaky people. Normally you do not want to compile hsc in debug mode. Therefor I am not going to explain many details about it, but it should be sufficient for those it is directed to.

In debug mode, hsc performs some additional plausibility checks. Most remarkable, it will check for unreleased resources and trashed memory. It will also output some statistic at the end of every run.

To compile it for this mode, you have to define two symbols called DEBUG and DEBUG_UGLY. After that, you can use the CLI option -DEBUG to enable this additional output.

It does not make sense to run hsc in debug mode all the time, as it is (even more) horrible slow in it. You should only use this if you want to trace internal error messages, some completely unreasonable behavior or crashes.

If you still can not get enough of debugging information, you can take a look at the source files hsclib/ldebug.h and ugly/udebug.h, where you can set some additional flags to 1.